focus-trap-react

What is focus-trap-react?

The focus-trap-react package is a React wrapper for the focus-trap library, which is used to manage focus within a DOM node. This is particularly useful for accessibility purposes, ensuring that keyboard navigation is contained within a specific area, such as a modal dialog or a dropdown menu.

What are focus-trap-react's main functionalities?

Basic Focus Trap

This example demonstrates a basic focus trap that contains three buttons. When the focus is within this div, it will be trapped and cannot move outside of it using keyboard navigation.

import React from 'react';
import FocusTrap from 'focus-trap-react';

const BasicFocusTrap = () => (
  <FocusTrap>
    <div>
      <button>Button 1</button>
      <button>Button 2</button>
      <button>Button 3</button>
    </div>
  </FocusTrap>
);

export default BasicFocusTrap;

Focus Trap with Initial Focus

This example shows a focus trap where the initial focus is set to a specific button using the `initialFocus` prop. When the focus trap is activated, the focus will automatically move to the button with the ID 'initial-focus'.

import React from 'react';
import FocusTrap from 'focus-trap-react';

const FocusTrapWithInitialFocus = () => (
  <FocusTrap initialFocus='#initial-focus'>
    <div>
      <button id='initial-focus'>Initial Focus Button</button>
      <button>Button 2</button>
      <button>Button 3</button>
    </div>
  </FocusTrap>
);

export default FocusTrapWithInitialFocus;

Focus Trap with Return Focus

This example demonstrates a focus trap that will return the focus to the element that activated it once the trap is deactivated. The `returnFocus` prop ensures that the focus goes back to the button that was clicked to activate the focus trap.

import React, { useState } from 'react';
import FocusTrap from 'focus-trap-react';

const FocusTrapWithReturnFocus = () => {
  const [isTrapActive, setIsTrapActive] = useState(false);

  return (
    <div>
      <button onClick={() => setIsTrapActive(true)}>Activate Focus Trap</button>
      {isTrapActive && (
        <FocusTrap returnFocus>
          <div>
            <button onClick={() => setIsTrapActive(false)}>Deactivate Focus Trap</button>
            <button>Button 2</button>
            <button>Button 3</button>
          </div>
        </FocusTrap>
      )}
    </div>
  );
};

export default FocusTrapWithReturnFocus;

Other packages similar to focus-trap-react

react-focus-lock

react-focus-lock is another React component that provides a focus management solution. It ensures that the focus stays within a specified area, similar to focus-trap-react. However, react-focus-lock offers additional features like auto-locking and focus restoration, making it a more feature-rich alternative.

react-aria-modal

react-aria-modal is a React component for creating accessible modal dialogs. It includes focus trapping as part of its functionality, ensuring that keyboard navigation is contained within the modal. While it is more specialized for modal dialogs, it provides a robust solution for focus management within modals.

react-modal

react-modal is a widely-used React component for creating modals. It includes built-in focus management to trap focus within the modal when it is open. While it is primarily focused on modal dialogs, it offers a comprehensive solution for focus trapping within modals.

README

focus-trap-react

A React component that traps focus.

This component is a light wrapper around focus-trap, tailored to your React-specific needs.

You might want it for, say, building an accessible modal?

What it does

Check out the demo.

Please read the focus-trap documentation to understand what a focus trap is, what happens when a focus trap is activated, and what happens when one is deactivated.

This module simply provides a React component that creates and manages a focus trap.

• The focus trap automatically activates when mounted (by default, though this can be changed).
• The focus trap automatically deactivates when unmounted.
• The focus trap can be activated and deactivated, paused and unpaused via props.

Installation

npm install focus-trap-react

dist/focus-trap-react.js is the Babel-compiled file that you'll use.

React dependency

React >= 16.0.0.

Browser Support

Basically IE9+.

Why? Because this module's core functionality comes from focus-trap, which uses a couple of IE9+ functions.

Usage

You wrap any element that you want to act as a focus trap with the <FocusTrap> component. <FocusTrap> expects exactly one child element which can be any HTML element or other React component that contains focusable elements. It cannot be a Fragment because <FocusTrap> needs to be able to get a reference to the underlying HTML element, and Fragments do not have any representation in the DOM.

For example:

<FocusTrap>
  <div id="modal-dialog" className="modal" >
    <button>Ok</button>
    <button>Cancel</button>
  </div>
</FocusTrap>

<FocusTrap>
  <ModalDialog okButtonText="Ok" cancelButtonText="Cancel" />
</FocusTrap>

You can read further code examples in demo/ (it's very simple), and see how it works.

Here's one more simple example:

const React = require('react');
const ReactDOM = require('react-dom'); // React 16-17
const { createRoot } = require('react-dom/client'); // React 18
const FocusTrap = require('focus-trap-react');

class Demo extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      activeTrap: false
    };

    this.mountTrap = this.mountTrap.bind(this);
    this.unmountTrap = this.unmountTrap.bind(this);
  }

  mountTrap = () => {
    this.setState({ activeTrap: true });
  };

  unmountTrap = () => {
    this.setState({ activeTrap: false });
  };

  render() {
    const trap = this.state.activeTrap
      ? <FocusTrap
          focusTrapOptions={{
            onDeactivate: this.unmountTrap
          }}
        >
          <div className="trap">
            <p>
              Here is a focus trap
              {' '}
              <a href="#">with</a>
              {' '}
              <a href="#">some</a>
              {' '}
              <a href="#">focusable</a>
              {' '}
              parts.
            </p>
            <p>
              <button onClick={this.unmountTrap}>
                deactivate trap
              </button>
            </p>
          </div>
        </FocusTrap>
      : false;

    return (
      <div>
        <p>
          <button onClick={this.mountTrap}>
            activate trap
          </button>
        </p>
        {trap}
      </div>
    );
  }
}

ReactDOM.render(<Demo />, document.getElementById('root')); // React 16-17
createRoot(document.getElementById('root')).render(<Demo />); // React 18

Props

focusTrapOptions

Type: Object, optional

Pass any of the options available in focus-trap's createOptions.

⚠️ See notes about testing in JSDom (e.g. using Jest) if that's what you currently use.

active

Type: Boolean, optional

By default, the FocusTrap activates when it mounts. So you activate and deactivate it via mounting and unmounting. If, however, you want to keep the FocusTrap mounted while still toggling its activation state, you can do that with this prop.

See demo/demo-special-element.js.

paused

Type: Boolean, optional

If you would like to pause or unpause the focus trap (see focus-trap's documentation), toggle this prop.

containerElements

Type: Array of HTMLElement, optional

If passed in, these elements will be used as the boundaries for the focus-trap, instead of the child. These get passed as arguments to focus-trap's updateContainerElements() method.

Note that when you use containerElements, the need for a child is eliminated as the child is always ignored when the prop is specified, even if the prop is [] (an empty array). Also note that if the refs you're putting into the array like containerElements={[ref1.current, ref2.current]} and one or both refs aren't resolved yet, resulting in [null, null] for example, the trap will not get created. The array must contain at least one HTMLElement in order for the trap to get updated.

If containerElements is subsequently updated (i.e. after the trap has been created) to an empty array (or an array of falsy values like [null, null]), the trap will still be active, but the TAB key will do nothing because the trap will not contain any tabbable groups of nodes. At this point, the trap can either be deactivated manually or by unmounting, or an updated set of elements can be given to containerElements to resume use of the TAB key.

Using containerElements does require the use of React refs which, by nature, will require at least one state update in order to get the resolved elements into the prop, resulting in at least one additional render. In the normal case, this is likely more than acceptable, but if you really want to optimize things, then you could consider using focus-trap directly (see Trap2.js).

Help

Testing in JSDom

⚠️ JSDom is not officially supported. Your mileage may vary, and tests may break from one release to the next (even a patch or minor release).

This topic is just here to help with what we know may affect your tests.

In general, a focus trap is best tested in a full browser environment such as Cypress, Playwright, or Nightwatch where a full DOM is available.

Sometimes, that's not entirely desirable, and depending on what you're testing, you may be able to get away with using JSDom (e.g. via Jest), but you'll have to configure your traps using the focusTrapOptions.tabbableOptions.displayCheck: 'none' option.

See Testing focus-trap in JSDom for more details.

Contributing

See CONTRIBUTING.

Contributors

In alphabetical order:

Benjamin Koltes 🐛	Benjamin Tan 📖	Clint Goodman 💻 📖 💡 ⚠️	Daniel 🚧 ⚠️	Daniel Tonon 📖 💻 ⚠️	David Clark 💻 🐛 🚇 ⚠️ 📖 🚧	Dependabot 🚧
Johannes Ewald 💻	Jonathan Suzuki 🐛	Kathleen McMahon 🚧	LoganDark 🐛	Marais Rossouw 🚇	Misha Moroshko 🐛	Nate Liu ⚠️
Rivaldo Junior 🚧	Scott Rippey 💻 🐛	Sean McPherson 💻	Shane Moore 📦	Slapbox 📖 🐛	Stefan Cameron 💻 🐛 🚇 ⚠️ 📖 🚧	Tyler Hawkins 📖 💡 ⚠️ 🔧
Wandrille Verlut 💻 ⚠️	krikienoid 🐛	syntactic-salt 🐛

Changelog

9.0.2

Patch Changes

• 4d8e041: Fix an issue when running in strict mode which has React immediately unmount/remount the trap, causing it to deactivate and then have to reactivate (per existing component state) on the remount. #720